Server Watch Plugin SDK Date: 6 Feb 2004
Release: 1.0
Main Page | Class Hierarchy | Class List | File List | Class Members | File Members | Related Pages

ISWServerData Class Reference

#include <ISWServerData.h>

List of all members.


Detailed Description

Contains the server data that will be outputed to the user and provides an API for retrieving and setting the current server information. The data in this class should be set during the "Ping" process in the plugin. It can be read at any time.

Server Watch will generate an instance of this class automatically. You will not need to store instances of this class as the appropriate instance will be passed into the plugin as a member of an SWPluginServerStruct when the plugin is expected to handle a server specific event.

Thread safety design:
This class is used in a highly threaded environment, therefore it is important that users of this class use the concurrency functions of this class correctly. You can read more about the concurrency design in the "Concurrency" section below. If these functions are not used correctly, your plugin will not work as you expect. The concurrency design of this class differs in important ways from ISWServerSettings, so you should understand both.

Bug:
If you pass an invalid table id string into any of the table functions, with the exception of TableExists(), Server Watch will crash.


Public Member Functions

Concurrency
Functions that manage the transaction based reader/writer thread safety process

Unlike the concurency functionality of ISWServerSettings, the concurrency of this class follows a very modified version of the readers/writers pattern (see ISWServerSettings for a good description of the classic pattern). It must be possible to read and write runtime data at the same time. To do otherwise can cause long delays in the user interface. To accomplish this we have created the following design:

There is both a read buffer and a write buffer. Standard read functions ("get...", etc) read from the read buffer. All write functions ("set...", etc) write into the write buffer. The write buffer is copied into the read buffer when both of the following conditions are met: 1) EndWrite has been called and 2) there are no readers. EndWrite() blocks until there are no readers and the copy of the write buffer into the read buffer is complete.

What does this mean for every day use?

For the most part, everything works as expected. Multiple readers can read concurrently. Only one writer gains write access at a time, though they don't have to wait for the readers to exit. However, if a writer sets a value, the following standard fetch on that value will not necessarily retrieve the value that was set. Only when a call to EndWrite() has been completed will the read buffer be committed and guaruntee that the value fetched is the same as the value set.

If you need to access a value you have set before you can call EndWrite(), it is suggested that you cash that value locally until you can call EndWrite(). There are some functions designed to fetch data directly from the write buffer. These functions are desognated by titles in the form of "get...Uncommitted." They should be used carfully because missuse of these funtions invalidates the thread safety design of this class. Specifically, the calling thread of the function must have called ISWServerData::BeginWrite() on this class and must not have called ISWServerData::EndWrite() yet. In otherwords, the thread must own the write context. If you do not follow this restriction, you are "off the island" and will likely crash Server Watch in random ways that are difficult to reproduce and fix.

Remember that you only want to call EndWrite() when you have update ALL of the values you intend to update. If you do a partial update, another writer could beat you to the next BeginWrite() call and skew your data, or more likely a reader will come through while you are processing the rest and cause the display of only partially accurate information.

Note:
Technically, it is possible to fetch data from this class without calling BeginRead(), but doing so invalidates the data integrity guaranties of the class and could cause the program to crash. It is not possible to write to the class without previously calling BeginWrite().


virtual void BeginRead ()=0
 Puts the class in read mode.
virtual void EndRead ()=0
 Removes the class from read mode.
virtual void BeginWrite ()=0
 Puts the class in write mode.
virtual void EndWrite ()=0
 Removes the class from write mode.
virtual void Retain ()=0
 Retains the class for use.
virtual void Release ()=0
 Removes your retain rights for the class.
Basic Runtime Server Values
virtual SWRESULT SetServerName (std::wstring name)=0
 Sets the name of the server as reported by the server.
virtual std::wstring GetServerName () const =0
 The name of the server as reported by the server.
virtual SWRESULT SetMaxUsers (int users)=0
 Sets the reported maximum number of users that can be on the server.
virtual int GetMaxUsers () const =0
 Retrieves the maximum number of user that can be on the server.
virtual SWRESULT SetTotalUsers (int users)=0
 Sets the reported current number of users that are on the server.
virtual int GetTotalUsers () const =0
 Retrieves the current number of users on the server.
virtual SWRESULT SetAuxStat (std::wstring theStat)=0
 Sets the text to be diaplyed in the AuxStat box.
virtual std::wstring GetAuxStat () const =0
 The text to be displayed in the AuxStat box.
virtual SWRESULT SetStatusText (std::wstring theStatus)=0
 Sets the text to be displayed as the "status" display in Server Watch.
virtual std::wstring GetStatusText () const =0
 Returns the text that will be displayed in the "status" display box.
Tray Icon
The plugin manages the values that will be displayed in the tray icon for monitored servers. The icon itself is set by calling SetIconNumber(), SetIconUp(), or SetIconDown(). A call to any one of these functions will override the previous setting.
 // pData is a pointer to an instance of ISWServerData
 
 pData->BeginWrite();
 pData->SetIconNumber(10);
 pData->EndWrite();
 // Icon now displays 10

 pData->BeginWrite();
 pData->SetIconUp();
 pData->SetIconNumber(20);
 pData->EndWrite();
 // Icon now displays 20

 pData->BeginWrite();
 pData->SetIconDown();
 pData->EndWrite();
 // Icon now displays down symbol


virtual SWRESULT SetIconNumber (int num)=0
 Sets the icon number to be desplayed by Server Watch.
virtual int GetIconNumber () const =0
 The number to be displayed in the tray icon.
virtual SWRESULT SetIconUp ()=0
 Sets the icon to display the "up" icon.
virtual SWRESULT SetIconDown ()=0
 Sets the icon to display the "down" icon.
virtual SWRESULT SetIconTip (std::wstring theTip)=0
 Sets the text to be displayed as the "tip" for the tray icon.
virtual std::wstring GetIconTip () const =0
 Returns the text to be displayed as the "tip" for the tray icon.
Data Tables
Each data table is displayed in Server Watch as an individual server pane. You can specify one of these tables to be the User Table. This table has special significance to the system. For example, its first column will be searched for user set "buddies" that may be on the server. If the buddy is found, a special column in the display of the Users Table will display that that individual is a buddy and alerts will be triggered.

virtual SWRESULT CreateTable (const std::wstring &strTableID)=0
 Creates a new table identified by the string strTableID.
virtual const bool TableExists (const std::wstring &strTableID) const =0
 Tests whether or not a specified table exists.
virtual const std::wstring & GetTableName (const std::wstring &strTableID) const =0
 Retrieves the name of a specified table.
virtual SWRESULT SetTableName (const std::wstring &strTableID, const std::wstring &strName)=0
 Sets the number of a specified table.
virtual SWRESULT SetUsersTableID (const std::wstring &strName)=0
 Sets ID that will be used as the users table.
virtual const std::wstring & GetUsersTableID () const =0
 Retrieves the ID that will be used as the users table.
virtual SWRESULT SetNumCols (const std::wstring &strTableID, int NumCols)=0
 Sets the number of columns on a specified table.
virtual int GetNumCols (const std::wstring &strTableID) const =0
 Retrieves the number of columns on a specified table.
virtual SWRESULT SetColHeaderTitle (const std::wstring &strTableID, int index, const std::wstring &title)=0
 Sets the name to be displayed for a table on a specified table.
virtual SWRESULT GetColHeaderTitle (const std::wstring &strTableID, int index, std::wstring &title) const =0
 Retrieves the name of a column on a specified table.
virtual SWRESULT GetColDefaultWidth (const std::wstring &strTableID, int index, int &width) const =0
 Retrieves the default width of a column on a specified table.
virtual SWRESULT SetColDefaultWidth (const std::wstring &strTableID, int index, int width)=0
 Sets the number of columns on a specified table.
virtual SWRESULT SetColWidthToDefault (const std::wstring &strTableID)=0
 Forces all columns on a table to have a current width that is the same as their default width.
virtual int GetNumRows (const std::wstring &strTableID) const =0
 Retrieves the number of rows on a specified table.
virtual int GetNumRowsUncommitted (const std::wstring &strTableID) const =0
 Retrieves the uncommited number of rows on a specified table.
virtual SWRESULT ResetData (const std::wstring &strTableID)=0
 Removes all the rows from a specified table.
virtual SWRESULT AddRow (const std::wstring &strTableID)=0
 Adds a new row to a specified table.
virtual SWRESULT SetData (const std::wstring &strTableID, int col, int row, const std::wstring &data)=0
 Sets the value of a specified table cell.
virtual SWRESULT GetData (const std::wstring &strTableID, int col, int row, std::wstring &data) const =0
 Retrieves the value of a specified table cell.
virtual SWRESULT GetDataUncommitted (const std::wstring &strTableID, int col, int row, std::wstring &data) const =0
 Retrieves the uncommited value of a specified table cell.
Custom Panes
Server Watch allows plugins to define custom graphical panes.
See also:
ISWPluginPane


virtual SWRESULT InsertPane (ISWPluginPane *pane)=0


Member Function Documentation

virtual void ISWServerData::BeginRead  )  [pure virtual]
 

Puts the class in read mode.

This function blocks if a call to EndWrite() is causing the write buffer to be copied into the read buffer. It will unblock when that copy is complete.

virtual void ISWServerData::EndRead  )  [pure virtual]
 

Removes the class from read mode.

virtual void ISWServerData::BeginWrite  )  [pure virtual]
 

Puts the class in write mode.

You should update everything you intend to update before calling EndWrite(). Doing partial updates allows other threads to update the class and potential cause it to contain invalid data.

If you have called BeginWrite(), you should refrain from calling read functions. Writers are allowed to read, but they still read from the read buffer which is unlikely the functionality that you are expecting. This is different than the functionality in ISWServerSettings.

virtual void ISWServerData::EndWrite  )  [pure virtual]
 

Removes the class from write mode.

This function will block until there are no readers and the write buffer has been completely copied into the read buffer.

virtual void ISWServerData::Retain  )  [pure virtual]
 

Retains the class for use.

Call Retain on the class when you spawn a thread. This will allow you to use the class without fear of it being deleted while you are using it.

If you call retain, you must call Release when done with the class. If you do not match each Retain call with a call to release, this class will not be correctly cleaned up when Server Watch is quit.

virtual void ISWServerData::Release  )  [pure virtual]
 

Removes your retain rights for the class.

Only call Release if you have called Retain. Calling Release too many times will result in a crash in Server Watch. So, make sure your Release and Retain match up one-for-one.

virtual SWRESULT ISWServerData::SetServerName std::wstring  name  )  [pure virtual]
 

Sets the name of the server as reported by the server.

This is not the same as the UserSetServerName() defined in ISWServerSettings. That name is chosen by the user of Server Watch.

Returns:
SWResult defining the success of the function
Return values:
SW_OK The function completed successfully
SW_INCORRECTSTATE The class is not set to write mode with a call to BeginWrite()

virtual std::wstring ISWServerData::GetServerName  )  const [pure virtual]
 

The name of the server as reported by the server.

This is not the same as the UserSetServerName() defined in ISWServerSettings. That name is chosen by the user of Server Watch.

Returns:
The retrieved server name.

virtual SWRESULT ISWServerData::SetMaxUsers int  users  )  [pure virtual]
 

Sets the reported maximum number of users that can be on the server.

Returns:
SWResult defining the success of the function
Return values:
SW_OK The function completed successfully
SW_INCORRECTSTATE The class is not set to write mode with a call to BeginWrite()

virtual int ISWServerData::GetMaxUsers  )  const [pure virtual]
 

Retrieves the maximum number of user that can be on the server.

Returns:
The maximum number of users.

virtual SWRESULT ISWServerData::SetTotalUsers int  users  )  [pure virtual]
 

Sets the reported current number of users that are on the server.

Returns:
SWResult defining the success of the function
Return values:
SW_OK The function completed successfully
SW_INCORRECTSTATE The class is not set to write mode with a call to BeginWrite()

virtual int ISWServerData::GetTotalUsers  )  const [pure virtual]
 

Retrieves the current number of users on the server.

Returns:
The number of users on the server.

virtual SWRESULT ISWServerData::SetAuxStat std::wstring  theStat  )  [pure virtual]
 

Sets the text to be diaplyed in the AuxStat box.

Returns:
SWResult defining the success of the function
Return values:
SW_OK The function completed successfully
SW_INCORRECTSTATE The class is not set to write mode with a call to BeginWrite()

virtual std::wstring ISWServerData::GetAuxStat  )  const [pure virtual]
 

The text to be displayed in the AuxStat box.

Returns:
The AuxStat text.

virtual SWRESULT ISWServerData::SetStatusText std::wstring  theStatus  )  [pure virtual]
 

Sets the text to be displayed as the "status" display in Server Watch.

Returns:
SWResult defining the success of the function
Return values:
SW_OK The function completed successfully
SW_INCORRECTSTATE The class is not set to write mode with a call to BeginWrite()

virtual std::wstring ISWServerData::GetStatusText  )  const [pure virtual]
 

Returns the text that will be displayed in the "status" display box.

Returns:
The "status" text.

virtual SWRESULT ISWServerData::SetIconNumber int  num  )  [pure virtual]
 

Sets the icon number to be desplayed by Server Watch.

Only the values 0 - 9,999 are supported.

Returns:
SWResult defining the success of the function
Return values:
SW_OK The function completed successfully
SW_INCORRECTSTATE The class is not set to write mode with a call to BeginWrite()

virtual int ISWServerData::GetIconNumber  )  const [pure virtual]
 

The number to be displayed in the tray icon.

Returns:
The icon number to be displayed in the tray.

virtual SWRESULT ISWServerData::SetIconUp  )  [pure virtual]
 

Sets the icon to display the "up" icon.

Returns:
SWResult defining the success of the function
Return values:
SW_OK The function completed successfully
SW_INCORRECTSTATE The class is not set to write mode with a call to BeginWrite()

virtual SWRESULT ISWServerData::SetIconDown  )  [pure virtual]
 

Sets the icon to display the "down" icon.

Returns:
SWResult defining the success of the function
Return values:
SW_OK The function completed successfully
SW_INCORRECTSTATE The class is not set to write mode with a call to BeginWrite()

virtual SWRESULT ISWServerData::SetIconTip std::wstring  theTip  )  [pure virtual]
 

Sets the text to be displayed as the "tip" for the tray icon.

Returns:
SWResult defining the success of the function
Return values:
SW_OK The function completed successfully
SW_INCORRECTSTATE The class is not set to write mode with a call to BeginWrite()

virtual std::wstring ISWServerData::GetIconTip  )  const [pure virtual]
 

Returns the text to be displayed as the "tip" for the tray icon.

Returns:
The tray icon "tip" text.

virtual SWRESULT ISWServerData::CreateTable const std::wstring &  strTableID  )  [pure virtual]
 

Creates a new table identified by the string strTableID.

The tables will be displayed in the order created.

Parameters:
strTableID The name of the table to be created
Returns:
SWResult defining the success of the function
Return values:
SW_OK The function completed successfully
SW_INCORRECTSTATE The class is not set to write mode with a call to BeginWrite()
SW_INVALIDARG Requested table id is already in use

virtual const bool ISWServerData::TableExists const std::wstring &  strTableID  )  const [pure virtual]
 

Tests whether or not a specified table exists.

Parameters:
strTableID The name of the table
Returns:
Whether or not the requested table exists

virtual const std::wstring& ISWServerData::GetTableName const std::wstring &  strTableID  )  const [pure virtual]
 

Retrieves the name of a specified table.

The name of the table differes from the identifying string.

Parameters:
strTableID The name of the table
Returns:
The name of the table

virtual SWRESULT ISWServerData::SetTableName const std::wstring &  strTableID,
const std::wstring &  strName
[pure virtual]
 

Sets the number of a specified table.

The name of the table differes from the identifying string.

Parameters:
strTableID The name of the table
strName The new name for the table
Returns:
SWResult defining the success of the function
Return values:
SW_OK The function completed successfully
SW_INCORRECTSTATE The class is not set to write mode with a call to BeginWrite()

virtual SWRESULT ISWServerData::SetUsersTableID const std::wstring &  strName  )  [pure virtual]
 

Sets ID that will be used as the users table.

The primary difference between the users table and a regular table, is that the first column of the users table will be used for name searching during buddy identification. When displayed, the GUI will place an extra column indicator to display whether of not each row was identified as a buddy.

Parameters:
strName The ID that identifies teh users table
Returns:
SWResult defining the success of the function
Return values:
SW_OK The function completed successfully
SW_INCORRECTSTATE The class is not set to write mode with a call to BeginWrite()

virtual const std::wstring& ISWServerData::GetUsersTableID  )  const [pure virtual]
 

Retrieves the ID that will be used as the users table.

The primary difference between the users table and a regular table, is that the first column of the users table will be used for name searching during buddy identification. When displayed, the GUI will place an extra column indicator to display whether of not each row was identified as a buddy.

Returns:
The ID that will be used as the users table.

virtual SWRESULT ISWServerData::SetNumCols const std::wstring &  strTableID,
int  NumCols
[pure virtual]
 

Sets the number of columns on a specified table.

Parameters:
strTableID The name of the table
NumCols The number of columns the table will have
Returns:
SWResult defining the success of the function
Return values:
SW_OK The function completed successfully
SW_INCORRECTSTATE The class is not set to write mode with a call to BeginWrite()

virtual int ISWServerData::GetNumCols const std::wstring &  strTableID  )  const [pure virtual]
 

Retrieves the number of columns on a specified table.

Parameters:
strTableID The name of the table
Returns:
The number of columns the table has

virtual SWRESULT ISWServerData::SetColHeaderTitle const std::wstring &  strTableID,
int  index,
const std::wstring &  title
[pure virtual]
 

Sets the name to be displayed for a table on a specified table.

Parameters:
strTableID The name of the table
index The numeric id of the column (0 starts as the first column)
title The new title
Returns:
SWResult defining the success of the function
Return values:
SW_OK The function completed successfully
SW_INCORRECTSTATE The class is not set to write mode with a call to BeginWrite()
SW_OUTOFBOUNDS The index was invalid

virtual SWRESULT ISWServerData::GetColHeaderTitle const std::wstring &  strTableID,
int  index,
std::wstring &  title
const [pure virtual]
 

Retrieves the name of a column on a specified table.

Parameters:
strTableID The name of the table
index The numeric id of the column (0 starts as the first column)
title The string that will be set to the title if the function is successful
Returns:
SWResult defining the success of the function
Return values:
SW_OK The function completed successfully
SW_OUTOFBOUNDS The index was invalid. The variable passed into parameter "title" was not changed

virtual SWRESULT ISWServerData::GetColDefaultWidth const std::wstring &  strTableID,
int  index,
int &  width
const [pure virtual]
 

Retrieves the default width of a column on a specified table.

The default width is the width that the column starts with before the user modifies it.

Parameters:
strTableID The name of the table
index The numeric id of the column (0 starts as the first column)
width The int that will be set to the width if the function is successful
Returns:
SWResult defining the success of the function
Return values:
SW_OK The function completed successfully
SW_OUTOFBOUNDS The index was invalid. The variable passed into parameter "width" was not changed

virtual SWRESULT ISWServerData::SetColDefaultWidth const std::wstring &  strTableID,
int  index,
int  width
[pure virtual]
 

Sets the number of columns on a specified table.

The default width is the width that the column starts with before the user modifies it.

Parameters:
strTableID The name of the table
index The numeric id of the column (0 starts as the first column)
width The width to set the column to
Returns:
SWResult defining the success of the function
Return values:
SW_OK The function completed successfully
SW_INCORRECTSTATE The class is not set to write mode with a call to BeginWrite()
SW_OUTOFBOUNDSThe index was invalid

virtual SWRESULT ISWServerData::SetColWidthToDefault const std::wstring &  strTableID  )  [pure virtual]
 

Forces all columns on a table to have a current width that is the same as their default width.

It is not common for a plugin to call this. The historical reason for its inclusion in the plugin API is for the extremely rare occasion when all the columns of a table are removed because some value has changed on the server (version number, for instance), and all new columns were added. At that time the old columns' widths would still be in place which would usually look bad to the user.

Parameters:
strTableID The name of the table

virtual int ISWServerData::GetNumRows const std::wstring &  strTableID  )  const [pure virtual]
 

Retrieves the number of rows on a specified table.

This function returns the commited value. If you need the value for the uncommited state, use the Uncommited version of this function.

Parameters:
strTableID The name of the table
Returns:
The number of rows the table has
See also:
GetNumRowsUncommitted()

virtual int ISWServerData::GetNumRowsUncommitted const std::wstring &  strTableID  )  const [pure virtual]
 

Retrieves the uncommited number of rows on a specified table.

This function returns the uncommited value. If you need the value for the commited state, use the standard version of this function.

Parameters:
strTableID The name of the table
Returns:
The number of rows the table has GetNumRowsUncommitted()

virtual SWRESULT ISWServerData::ResetData const std::wstring &  strTableID  )  [pure virtual]
 

Removes all the rows from a specified table.

All row data will be reset, however, the columns will remain intact.

Parameters:
strTableID The name of the table
Returns:
SWResult defining the success of the function
Return values:
SW_OK The function completed successfully
SW_INCORRECTSTATE The class is not set to write mode with a call to BeginWrite()

virtual SWRESULT ISWServerData::AddRow const std::wstring &  strTableID  )  [pure virtual]
 

Adds a new row to a specified table.

The row is added to the end of the table.

Parameters:
strTableID The name of the table
Returns:
SWResult defining the success of the function
Return values:
SW_OK The function completed successfully
SW_INCORRECTSTATE The class is not set to write mode with a call to BeginWrite()

virtual SWRESULT ISWServerData::SetData const std::wstring &  strTableID,
int  col,
int  row,
const std::wstring &  data
[pure virtual]
 

Sets the value of a specified table cell.

A table cell is the intersection of a row and column in a table. Any string value is considered legal.

Parameters:
strTableID The name of the table
col The column that, when combined with the row, defines the table cell
row The row that, when combined with the column, defines the table cell
data The string value for the cell
Returns:
SWResult defining the success of the function
Return values:
SW_OK The function completed successfully
SW_INCORRECTSTATE The class is not set to write mode with a call to BeginWrite()

virtual SWRESULT ISWServerData::GetData const std::wstring &  strTableID,
int  col,
int  row,
std::wstring &  data
const [pure virtual]
 

Retrieves the value of a specified table cell.

A table cell is the intersection of a row and column in a table.

This function returns the commited value. If you need the value for the uncommited state, use the Uncommited version of this function.

Parameters:
strTableID The name of the table
col The column that, when combined with the row, defines the table cell
row The row that, when combined with the column, defines the table cell
data A string that will contain the value for the cell
Returns:
SWResult defining the success of the function
Return values:
SW_OK The function completed successfully

virtual SWRESULT ISWServerData::GetDataUncommitted const std::wstring &  strTableID,
int  col,
int  row,
std::wstring &  data
const [pure virtual]
 

Retrieves the uncommited value of a specified table cell.

A table cell is the intersection of a row and column in a table.

This function returns the uncommited value. If you need the value for the commited state, use the standard version of this function.

Parameters:
strTableID The name of the table
col The column that, when combined with the row, defines the table cell
row The row that, when combined with the column, defines the table cell
data A string that will contain the value for the cell
Returns:
SWResult defining the success of the function
Return values:
SW_OK The function completed successfully
SW_INCORRECTSTATE The class is not set to write mode with a call to BeginWrite()

virtual SWRESULT ISWServerData::InsertPane ISWPluginPane pane  )  [pure virtual]
 

Inserts a class that implements ISWPluginPane into the list of panes related to the server.

Returns:
SWResult defining the success of the function
Return values:
SW_OK The function completed successfully
SW_INCORRECTSTATE The class is not set to write mode with a call to BeginWrite()


The documentation for this class was generated from the following file:

Copyright (c) 2003-2004, Deep Fried Software. All rights reserved.